/*
 * MIT License
 *
 * Copyright (c) 2020 wen.gu <454727014@qq.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/***************************************************************************
 * Name: avp_thread.h
 *
 * Purpose: the thread wrapper for av player
 *
 * Developer:
 *   wen.gu , 2022-01-19
 *
 * TODO:
 *
 ***************************************************************************/

/******************************************************************************
 **    INCLUDES
 ******************************************************************************/
#ifndef __AVP_THREAD_H__
#define __AVP_THREAD_H__

#include "avp_type.h"
#include "avp_error.h"

/******************************************************************************
 **    MACROS
 ******************************************************************************/


/******************************************************************************
 **    TYPE DEFINITIONS
 ******************************************************************************/
G_C_HEADER_START


typedef GPTR avp_thread_t;


typedef void (*avp_thread_func)(GPTR opaque);
/******************************************************************************
 **    CLASSES/FUNCTIONS DEFINITIONS
 ******************************************************************************/

/**
 * @brief create a thread instance with the thread func and a user opaque
 * 
 * @param func [in] the thread running function
 * @param opaque [in] a user private argument for thread function
 * @return avp_thread_t  the thread instance, if failed, return NULL
 */
G_API avp_thread_t avp_thread_create(avp_thread_func func, GPTR opaque);

/**
 * @brief join(wait) and destroy a thread instance
 * 
 * @param thd [in] the thread instance
 * @return void
 * @note this API maybe block forever if avp_thread_func not return
 */
G_API void avp_thread_join(avp_thread_t thd);

/**
 * @brief start to run the given thread, which must have been initialized
 * 
 * @param thd [in] the thread instance
 * @return void 
 */
G_API void avp_thread_run(avp_thread_t thd);

/**
 * @brief set a short name for the thread
 * 
 * @param thd  [in] the thread instance, if this arg is NULL, then is set the name for current thread which called this PAI
 * @param name [in] the name of thread
 * @return void
 */
G_API void avp_thread_set_name(avp_thread_t thd, const GSTR name);

/**
 * @brief get the name of the thread
 * 
 * @param thd [in] the thread instance, if this arg is NULL, then is get the name of current thread which called this API
 * @return const GPTR  the name of the thread, if failed, then return empty string ' return ""; '
 * @note   the return c string must do free after use. 
 */
G_API const GSTR avp_thread_name(avp_thread_t thd);


/**
 * @brief set a priority for the thread
 * 
 * @param thd      [in] the thread instance,if this arg is NULL, then is set priority for current thread which called this PAI
 * @param priority [in] the priority of thread
 * @return void
 */
G_API void avp_thread_set_priority(avp_thread_t thd, GS32 priority);

/**
 * @brief get the priority of the thread
 * 
 * @param thd  [in] the thread instance, if this arg is NULL, then is get the priority of current thread which called this API
 * @param priority [io] the priority of thread
 * @return GErrc  success: G_OK, else error code @see GErrc
 */
G_API GErrc avp_thread_priority(avp_thread_t thd, GS32* priority);

/**
 * @brief check the thread is current running thread
 * 
 * @param thd [in] the thread instance, if this arg is NULL, then always return GTRUE
 * @return GBOL GTRUE: the thread instance is current running thread, GFALSE: not current running thread
 */
G_API GBOL avp_thread_is_self(avp_thread_t thd);

/**
 * @brief do sleep in milli-second unit
 * 
 * @param time_ms [in] how long to sleep
 * @return void
 */
G_API void avp_thread_sleep(GU32 time_ms);



G_C_HEADER_END



#endif /** !__AVP_THREAD_H__ */

